---
title: Imágenes
description: Aprende cómo usar imágenes en Astro.
i18nReady: true
---
import Since from '~/components/Since.astro';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import Badge from '~/components/Badge.astro';
import RecipeLinks from "~/components/RecipeLinks.astro";

¡Astro ofrece varias formas para que uses imágenes en tu sitio, ya sea que estén almacenadas localmente dentro de tu proyecto, enlazadas desde una URL externa o gestionadas en un CMS o CDN!

## Dónde guardar las imágenes

### `src/` vs. `public/`

Recomendamos que las imágenes locales se mantengan en `src/` cuando sea posible, para que Astro pueda transformar, optimizar y empaquetarlas. Los archivos en el directorio `/public` siempre se sirven o copian tal como están en la carpeta de construcción, sin ningún procesamiento.

Tus imágenes locales almacenadas en `src/` pueden ser utilizadas por todos los archivos en tu proyecto: `.astro`, `.md`, `.mdx`, `.mdoc` y otros frameworks UI. Las imágenes pueden almacenarse en cualquier carpeta, incluida junto a tu contenido.

Almacena tus imágenes en la carpeta `public/` si deseas evitar cualquier tipo de procesamiento o para tener un enlace público directo a ellas.

### Imágenes remotas

También puedes optar por almacenar tus imágenes de forma remota, en un sistema de gestión de contenido (CMS) o en una plataforma de gestión de assets digitales (DAM).

Para una protección adicional al tratar con fuentes externas, las imágenes remotas solo se procesarán desde [fuentes de imágenes autorizadas](#autorizando-imágenes-remotas) especificadas en tu configuración. Sin embargo, cualquier imagen remota puede ser mostrada.

Astro puede obtener tus datos de forma remota utilizando APIs o mostrar imágenes desde su ruta completa de URL. Consulta nuestras [guías de CMS](/es/guides/cms/) para ejemplos de integración con servicios comunes.


## Imágenes en archivos `.astro`

En archivos `.astro`, **las imágenes locales deben ser importadas al archivo para poder ser utilizadas**. Las imágenes remotas y las imágenes en `public/` no requieren ser importadas

Importa y utiliza el componente incorporado `<Image />` de Astro para imágenes optimizadas usando `astro:assets`. Alternativamente, la sintaxis de Astro admite escribir directamente una etiqueta HTML `<img>`, lo que omite el procesamiento de imágenes

```astro title="src/pages/blog/MyImages.astro"
---
import { Image } from 'astro:assets';
import localBirdImage from '../../images/subfolder/localBirdImage.png';
---
<Image src={localBirdImage} alt="Un pájaro sentado sobre un nido de huevos."/>
<Image src="/images/bird-in-public-folder.jpg" alt="Un pájaro." width="50" height="50"/>
<Image src="https://example.com/remote-bird.jpg" alt="Un pájaro." width="50" height="50"/>

<img src={localBirdImage.src} alt="Un pájaro sentado sobre un nido de huevos.">
<img src="/images/bird-in-public-folder.jpg" alt="Un pájaro.">
<img src="https://example.com/remote-bird.jpg" alt="Un pájaro.">
```

Para importar imágenes dinámicamente desde la carpeta `src/`, consulta la siguiente receta:

<RecipeLinks slugs={["es/recipes/dynamically-importing-images" ]}/>

### `<Image />` (`astro:assets`)

Utiliza el componente integrado `<Image />` de Astro para mostrar versiones optimizadas de tus imágenes locales y [imágenes remotas configuradas](#autorizando-imágenes-remotas).

Las imágenes en la carpeta `public/`, así como las imágenes remotas no configuradas específicamente en tu proyecto, también se pueden usar con el componente Image, pero no se procesarán.

`<Image />` puede transformar las dimensiones, el tipo de archivo y la calidad de una imagen local o remota autorizada para un control sobre la imagen que se muestra. La etiqueta resultante `<img>` incluye atributos `alt`, `loading` y `decoding`, e infiere las dimensiones de la imagen para evitar el **Desplazamiento Acumulativo de Diseño (CLS)**.

:::tip[¿Qué es el Desplazamiento Acumulativo de Diseño?]
[Desplazamiento Acumulativo de Diseño (CLS)](https://web.dev/cls/) es una métrica de Core Web Vital para medir cuánto se ha desplazado el contenido de tu página durante la carga. El componente `<Image />` optimiza para el CLS al establecer automáticamente el `ancho` y el `alto` correctos para tus imágenes locales.
:::

```astro title="src/components/MyComponent.astro"
---
// Importa el componente Image y la imagen 
import { Image } from 'astro:assets';
import myImage from "../assets/my_image.png"; // La imagen es 1600x900
---

<!-- `alt` es obligatorio en el componente Imagen -->
<Image src={myImage} alt="Una descripción de mi imagen." />
```

```html
<!-- Salida -->
<!-- La imagen está optimizada, se aplican los atributos adecuados-->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  alt="Una descripción de mi imagen."
/>
```

#### Propiedades

##### src (requerido)

El formato del valor `src` de tu archivo de imagen depende de dónde esté ubicado tu archivo de imagen:

- **Imágenes locales en `src/`** - también debes **importar la imagen** utilizando una ruta de archivo relativa o configurar y usar un [alias de importación](/es/guides/aliases/). Luego usa el nombre de importación como valor de `src`:

  ```astro title="src/pages/index.astro" "myImportedImage" "{myImportedImage}"
  ---
  import { Image } from 'astro:assets';
  import myImportedImage from `../assets/my-local-image.png`
  ---
  <Image src={myImportedImage} alt="texto descriptivo" />
  ```

- **Imágenes en la carpeta `public/`** - utiliza la **ruta de archivo de la imagen relativa a la carpeta public**:

  ```astro title="src/pages/index.astro" '"/images/my-public-image.png"'
  ---
  import { Image } from 'astro:assets';
  ---
  <Image
    src="/images/my-public-image.png"
    alt="texto descriptivo"
    width="200"
    height="150"
  />
  ```

- **Imágenes remotas** - utiliza la **URL completa** de la imagen como valor de la propiedad:

  ```astro title="src/pages/index.astro" '"https://example.com/remote-image.jpg"'
  ---
  import { Image } from 'astro:assets';
  ---
  <Image
    src="https://example.com/remote-image.jpg"
    alt="texto descriptivo"
    width="200"
    height="150" />
  ```

##### alt (requerido)

Utiliza el atributo `alt` requerido para proporcionar un [texto alternativo descriptivo](https://www.w3.org/WAI/tutorials/images/) para las imágenes.

Si una imagen es meramente decorativa (es decir, no contribuye a la comprensión de la página), establece `alt=""` para que los lectores de pantalla y otras tecnologías de asistencia sepan que deben ignorar la imagen.

##### width y height (requerido para imágenes en `public/`)

Estas propiedades definen las dimensiones a utilizar para la imagen.

Cuando se utilizan imágenes en su relación de aspecto original, `width` y `height` son opcionales. Estas dimensiones pueden inferirse automáticamente de archivos de imagen ubicados en `src/` y de imágenes remotas con [`inferSize` establecido en `true`](#infersize).

Sin embargo, ambas de estas propiedades son necesarias para imágenes almacenadas en tu carpeta `public/`, ya que Astro no puede analizar estos archivos.

##### densities

<p><Since v="3.3.0" /></p>

Una lista de densidades de píxeles para generar la imagen.

Si se proporciona, este valor se utilizará para generar un atributo `srcset` en la etiqueta `<img>`. No proporciones un valor para `widths` cuando utilices este valor.

Las densidades que sean iguales a los anchos mayores que la imagen original se ignorarán para evitar el escalado de la imagen.

```astro title="src/components/MyComponent.astro"
---
import { Image } from 'astro:assets';
import myImage from "../assets/my_image.png";
---
<Image src={myImage} width={myImage.width / 2} densities={[1.5, 2]} alt="Una descripción de mi imagen." />
```

```html
<img
  src="/_astro/my_image.hash.webp"
  srcset="
    /_astro/my_image.hash.webp 1.5x
    /_astro/my_image.hash.webp 2x
  "
  alt="Una descripción de mi imagen"
  width="800"
  height="450"
  loading="lazy"
  decoding="async"
/>
```

##### widths

<p><Since v="3.3.0" /></p>

Una lista de anchos para generar la imagen.

Si se proporciona, este valor se utilizará para generar un atributo `srcset` en la etiqueta `<img>`. También se debe proporcionar una propiedad [`sizes`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/sizes).

No proporciones un valor para `densities` cuando utilices este valor. Solo uno de estos dos valores se puede utilizar para generar un `srcset`.

Los anchos que sean mayores que la imagen original se ignorarán para evitar el escalado de la imagen.

```astro
---
import { Image } from 'astro:assets';
import myImage from "../assets/my_image.png"; // La imagen es de 1600x900
---
<Image 
  src={myImage} 
  widths={[240, 540, 720, myImage.width]} 
  sizes={`(max-width: 360px) 240px, (max-width: 720px) 540px, (max-width: 1600px) 720px, ${myImage.width}px`} 
  alt="Una descripción de mi imagen." 
/>
```

```html
<img
  src="/_astro/my_image.hash.webp"
  srcset="
    /_astro/my_image.hash.webp 240w,
    /_astro/my_image.hash.webp 540w,
    /_astro/my_image.hash.webp 720w,
		/_astro/my_image.hash.webp 1600w
  "
  sizes="
    (max-width: 360px) 240px,
    (max-width: 720px) 540px,
    (max-width: 1600px) 720px,
    1600px
  "
  alt="Una descripción de mi imagen."
  width="1600"
  height="900"
  loading="lazy"
  decoding="async"
/>
```

##### format

Puedes opcionalmente indicar el [tipo de archivo de imagen](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types#common_image_file_types) de salida que se va a utilizar.

Por defecto, el componente `<Image />` producirá un archivo `.webp`.

##### quality

`quality` es una propiedad opcional que puede ser:
- un preajuste (`low`, `mid`, `high`, `max`) que se normaliza automáticamente entre los formatos.
- un número del `0` al `100` (interpretado de manera diferente entre los formatos).

##### inferSize

<p><Since v="4.4.0" /></p>

Te permite establecer automaticamente el `width` y `height` original de una imagen remota.

Por defecto, este valor está establecido en `false` y debes especificar manualmente ambas dimensiones para tus imágenes remotas.

Agrega `inferSize` al componente `<Image />` (o `inferSize: true` a `getImage()`) para inferir estos valores del contenido de la imágen cuando se obtiene. Esto es útil si no conoces las dimensiones de la imagen remota, o si éstas pueden cambiar:

```astro mark="inferSize"
---
import { Image } from 'astro:assets';
---
<Image src="https://example.com/cat.png" inferSize alt="Un gato durmiendo al sol.">
```

`inferSize` puede obtener las dimensiones de una [imagen remota de un dominio que no ha sido autorizado](#autorizando-imágenes-remotas), sin embargo la imagen en sí permanecerá sin procesar.

##### Propiedades adicionales

Además de las propiedades mencionadas anteriormente, el componente `<Image />` acepta todas las propiedades aceptadas por la etiqueta HTML `<img>`.

Por ejemplo, puedes proporcionar una propiedad `class` al elemento `<img>` final.

```astro title="src/pages/index.astro"
---
import { Image } from 'astro:assets';
import myImage from "../assets/my_image.png";
---

<!-- `alt` es obligatorio en el componente Imagen -->
<Image src={myImage} alt="" class="mi-clase" />
```

```html
<!-- Salida -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  class="mi-clase"
  alt=""
/>
```

#### Estableciendo valores por defecto

Actualmente, no hay forma de especificar valores predeterminados para todos los componentes `<Image />`. Los atributos requeridos deben establecerse en cada componente individual.

Como alternativa, puedes envolver estos componentes en otro componente de Astro para reutilizarlos. Por ejemplo, podrías crear un componente para las imágenes de tus entradas de blog:

```astro title="src/components/BlogPostImage.astro"
---
import { Image } from 'astro:assets';

const {src, ...attrs} = Astro.props;
---
<Image src={src} {...attrs} />

<style>
  img :global(img), svg {
    margin-block: 2.5rem;
    border-radius: 0.75rem;
  }
</style>
```

### `<Picture />`

<p><Since v="3.3.0" /></p>

Usa el componente `<Picture />` incorporado de Astro para mostrar una imagen receptiva con varios formatos y/o tamaños.

```astro title="src/pages/index.astro"
---
import { Picture } from 'astro:assets';
import myImage from "../assets/my_image.png"; // La imagen es de 1600x900
---

<!-- `alt` es obligatorio en el componente Picture -->
<Picture src={myImage} formats={['avif', 'webp']} alt="Una descripción de mi imagen." />
```

```html
<!-- Salida -->
<picture>
  <source srcset="/_astro/my_image.hash.avif" type="image/avif" />
  <source srcset="/_astro/my_image.hash.webp" type="image/webp" />
  <img
    src="/_astro/my_image.hash.png"
    width="1600"
    height="900"
    decoding="async"
    loading="lazy"
    alt="Una descripción de mi imagen."
  />
</picture>
```

#### Propiedades

`<Picture />` acepta todas las propiedades del componente `<Image />`, más las siguientes:

##### `formats`

Un arreglo de formatos de imagen para usar en las etiquetas `<source>`. Las entradas se agregarán como elementos `<source>` en el orden en que se enumeran, y este orden determina qué formato se muestra. Para obtener el mejor rendimiento, enumera el formato más moderno primero (por ejemplo, `webp` o `avif`). Por defecto, esto se establece en `['webp']`.

##### `fallbackFormat`

Formato que se utilizará como valor de respaldo para la etiqueta `<img>`.

El valor predeterminado es `.png` para imágenes estáticas (o `.jpg` si la imagen es un archivo JPG), `.gif` para imágenes animadas y `.svg` para archivos SVG.

##### `pictureAttributes`

Un objeto de atributos que se agregarán a la etiqueta `<picture>`.

Usa esta propiedad para aplicar atributos al elemento `<picture>` externo. Los atributos aplicados al componente `<Picture />` directamente se aplicarán al elemento `<img>` interno, excepto aquellos utilizados para la transformación de imágenes.

```astro title="src/components/MyComponent.astro"
---
import { Picture } from "astro:assets";
import myImage from "../my_image.png"; // La imagen es de 1600x900
---

<Picture src={myImage} alt="Una descripción de mi imagen." pictureAttributes={{style: "background-color: red;"}} />
```

```html
<picture style="background-color: red;">
  <source srcset="/_astro/my_image.hash.webp" type="image/webp" />
  <img
    src="/_astro/my_image.hash.png"
    alt="Una descripción de mi imagen."
    width="1600"
    height="900"
    loading="lazy"
    decoding="async"
  />
</picture>
```

### `<img>`

La [sintaxis de Astro](/es/basics/astro-syntax/) también admite escribir directamente una etiqueta `<img>`, con control total sobre su salida final. Estas imágenes no se procesarán ni optimizarán.

Esta acepta todas las propiedades de la etiqueta HTML `<img>`, y la única propiedad requerida es `src`.

#### Imágenes locales en `src/`

Las imágenes locales deben ser **importadas desde la ruta relativa** al archivo `.astro` existente, o configurar y usar un [alias de importación](/es/guides/aliases/). Luego, puedes acceder a la propiedad `src` de la imagen y otras propiedades para usar en la etiqueta `<img>`.

Por ejemplo, utiliza las propiedades `height` y `width` propias de la imagen para evitar CLS y mejorar los Core Web Vitals.

```astro title="src/pages/posts/post-1.astro" "myDog.width" "myDog.height"
---
// importar imágenes locales
import myDog from `../../images/pets/local-dog.jpg`
---
// acceder a las propiedades de la imagen
<img src={myDog.src} width={myDog.width} height={myDog.height} alt="Un perro ladrando." />
```

Los activos de imagen importados coinciden con la siguiente firma:

```ts
interface ImageMetadata {
  src: string;
  width: number;
  height: number;
  format: string;
}
```

#### Imágenes en `public/`

Para las imágenes ubicadas dentro de `public/`, utiliza la **ruta de archivo relativa a la carpeta public** de la imagen como valor de `src`:

```astro '"/images/public-cat.jpg"'
<img src="/images/public-cat.jpg" alt="Un gato dormiendo.">
```

#### Imágenes remotas

Para las imágenes remotas, utiliza la **URL completa** de la imagen como valor de `src`:

```astro '"https://example.com/remote-cat.jpg"'
<img src="https://example.com/remote-cat.jpg" alt="Un gato dormiendo.">
```

### Eligiendo `<Image />` vs `<img>`

El componente `<Image />` optimiza tu imagen e infiere el ancho y el alto (en imágenes locales) en función de la relación de aspecto original para evitar CLS. Sin embargo, solo funciona con ciertos formatos y no proporciona un elemento `<picture>`, ni admite `srcset`.

Utiliza el elemento HTML `<img>` cuando no puedas usar el componente `<Image />`, por ejemplo:
  - para formatos de imagen no admitidos
  - cuando no deseas que tu imagen se optimice mediante Astro
  - para acceder y cambiar el atributo `src` dinámicamente en el lado del cliente

### Autorizando imágenes remotas

Puedes configurar listas de dominios y patrones de URL de origen de imágenes autorizados para la optimización de imágenes utilizando [`image.domains`](/es/reference/configuration-reference/#imagedomains) y [`image.remotePatterns`](/es/reference/configuration-reference/#imageremotepatterns). Esta configuración es una capa adicional de seguridad para proteger tu sitio al mostrar imágenes desde una fuente externa.

Remote images from other sources will not be optimized, but using the `<Image />` component for these images will prevent Cumulative Layout Shift (CLS).

For example, the following configuration will only allow remote images from `astro.build` to be optimized:

```ts
// astro.config.mjs
export default defineConfig({
  image: {
    domains: ["astro.build"],
  }
});
```

La siguiente configuración solo permitirá que las imágenes remotas provengan de hosts HTTPS:

```ts
// astro.config.mjs
export default defineConfig({
  image: {
    remotePatterns: [{ protocol: "https" }],
  }
});
```

## Utilizando imágenes de un CMS o CDN

Los CDNs de imágenes funcionan con todas las opciones de imágenes de Astro. Utiliza la URL completa de la imagen como atributo `src` en el componente `<Image />`, una etiqueta `<img>` o en la notación Markdown. Para la optimización de imágenes con imágenes remotas, también [configura tus dominios autorizados o patrones de URL](#autorizando-imágenes-remotas).

Alternativamente, si el CDN proporciona un SDK de Node.js, puedes utilizarlo en tu proyecto. Por ejemplo, el SDK de [Cloudinary](https://cloudinary.com/documentation/node_integration) puede generar una etiqueta `<img>` con el `src` adecuado por ti.

## Imágenes en archivos Markdown

Utiliza la sintaxis estándar de Markdown `![alt](src)` en tus archivos `.md`. Esta sintaxis funciona con la [API de servicio de imagenes](/es/reference/image-service-reference/) de Astro para optimizar tus imágenes locales y las imágenes remotas autorizadas.

```md
<!-- src/pages/post-1.md -->

# Mi página Markdown

<!-- Imagen local almacenada en src/assets/ -->
<!-- Utiliza una ruta de archivo relativa o un alias de importación -->
![Un cielo estrellado.](../assets/stars.png)

<!-- Imagen almacenada en public/images/ -->
<!-- Utiliza la ruta de archivo relativa a public/ -->
![Un cielo estrellado.](/images/stars.png)

<!-- Imagen remota en otro servidor -->
<!-- Utiliza la URL completa de la imagen -->
![Astro](https://example.com/images/remote-image.png)
```

La etiqueta `<img>` no es compatible para imágenes locales y el componente `<Image />` no está disponible en archivos `.md`.

Si necesitas más control sobre los atributos de tus imágenes, te recomendamos utilizar el formato de archivo `.mdx`, que te permite incluir el componente `<Image />` de Astro o una etiqueta JSX `<img />` además de la sintaxis Markdown. Utiliza la [integración MDX](/es/guides/integrations-guide/mdx/) para agregar soporte para MDX en Astro.

## Imágenes en archivos MDX

Puedes utilizar el componente `<Image />` de Astro y las etiquetas JSX `<img />` en tus archivos `.mdx` importando tanto el componente como tu imagen. Úsalos tal como se [utilizan en archivos `.astro`](#imágenes-en-archivos-astro).

Además, hay soporte para la [sintaxis estándar de Markdown `![alt](src)`](#imágenes-en-archivos-markdown) sin necesidad de importación.

```mdx title="src/pages/post-1.mdx"
---
title: Título de mi página
---
import { Image } from 'astro:assets';
import rocket from '../assets/rocket.png';

# Mi Página MDX

// Imagen local almacenada en src/assets/
<Image src={rocket} alt="Un cohete en el espacio."/>
<img src={rocket.src} alt="Un cohete en el espacio." />
![A rocketship in space](../assets/rocket.png)

// Imagen almacenada en public/images/
<Image src="/images/stars.png" alt="Un cielo estrellado." />
<img src="/images/stars.png" alt="Un cielo estrellado." />
![Un cielo estrellado.](/images/stars.png)

// Imagen remota en otro servidor
<Image src="https://example.com/images/remote-image.png" />
<img src="https://example.com/images/remote-image.png" />
![Astro](https://example.com/images/remote-image.png)

```

## Imágenes en colecciones de contenido

Las imágenes en colecciones de contenido se procesarán de la misma manera que lo hacen en [Markdown](#imágenes-en-archivos-markdown) y [MDX](#imágenes-en-archivos-mdx) dependiendo del tipo de archivo que estés utilizando.

Además, puedes declarar una imagen asociada para una entrada de colecciones de contenido, así como la imagen de portada de una publicación de un blog, en el encabezado utilizando su ruta relativa a la carpeta actual:

```md title="src/content/blog/my-post.md" {3}
---
title: "Mi primera entrada en el blog"
cover: "./firstpostcover.jpeg" # se resolverá como "src/content/blog/firstblogcover.jpeg"
coverAlt: "Una fotografía de una puesta de sol detrás de una cordillera."
---

Esta es una entrada de blog
```

El helper `image` para el esquema de colecciones de contenido te permite validar los metadatos de la imagen utilizando Zod.

```ts title="src/content/config.ts"
import { defineCollection, z } from "astro:content";

const blogCollection = defineCollection({
	schema: ({ image }) => z.object({
		title: z.string(),
		cover: image().refine((img) => img.width >= 1080, {
			message: "¡La imagen de portada debe tener al menos 1080 píxeles de ancho!",
		}),
		coverAlt: z.string(),
	}),
});

export const collections = {
	blog: blogCollection,
};
```

La imagen se importará y transformará en metadatos, lo que te permitirá pasarlo como `src` a `<Image/>`, `<img>` o `getImage()`.

El siguiente ejemplo muestra una página de índice de un blog que muestra la foto de portada y el título de cada entrada del blog a partir del esquema anterior:

```astro title="src/pages/blog.astro" {10}
---
import { Image } from "astro:assets";
import { getCollection } from "astro:content";
const allBlogPosts = await getCollection("blog");
---

{
	allBlogPosts.map((post) => (
		<div>
			<Image src={post.data.cover} alt={post.data.coverAlt} />
			<h2>
				<a href={"/blog/" + post.slug}>{post.data.title}</a>
			</h2>
		</div>
	))
}
```

## Imágenes en componentes de frameworks UI

Cuando añadas imágenes en un componente de un framework UI, utiliza la sintaxis de imagen propia del framework para renderizar una imagen (p. ej. `<img/>` en JSX, `<img>` en Svelte).

Las imágenes locales deben **ser importadas primero** para acceder a sus [propiedades de imagen](#imágenes-locales-en-src) como `src`.

```jsx title="src/components/ReactImage.jsx"
import stars from "../assets/stars.png"

export default function ReactImage () {
  return (
    <img src={stars.src} alt="Un cielo estrellado." />
  )
}
```

```svelte title="src/components/SvelteImage.svelte"
<script>
  import stars from '../assets/stars.png'
</script>

<img src={stars.src} alt="Un cielo estrellado." />

```

#### Pasando el componente Image

El componente `<Image />`, al igual que cualquier otro componente de Astro, **no está disponible para los componentes de frameworks UI**.

Sin embargo, puedes pasar el contenido estático generado por `<Image />` a un componente de framework dentro de un archivo `.astro` como hijos o utilizando un [`<slot/>` nombrado](/es/guides/framework-components/#puedo-usar-componentes-de-astro-dentro-de-mis-componentes-de-framework):


```astro title="ImageWrapper.astro"
---
import ReactComponent from './ReactComponent.jsx';
import { Image } from "astro:assets"
import stars from "~/stars/docline.png";
---

<ReactComponent>
  <Image src={stars} alt="Un cielo estrellado." />
</ReactComponent>
```

## Generando imágenes con `getImage()`

:::caution
`getImage()` se basa en APIs solo para el servidor y provoca errores en la compilación cuando se utiliza en el lado del cliente.
:::

La función `getImage()` está destinada a generar imágenes que se utilizarán en otro lugar que no sea directamente en HTML, por ejemplo, en una [Ruta API](/es/guides/endpoints/#endpoints-del-servidor-rutas-de-api). También te permite crear tu propio componente `<Image />` personalizado.

<RecipeLinks slugs={["es/recipes/build-custom-img-component" ]}/>

`getImage()` recibe un objeto de opciones con las [mismas propiedades que el componente Image](#propiedades) (excepto `alt`).

```astro
---
import { getImage } from "astro:assets";
import myBackground from "../background.png"

const optimizedBackground = await getImage({src: myBackground, format: 'webp'})
---

<div style={`background-image: url(${optimizedBackground.src});`}></div>
```

Devuelve un objeto con las siguientes propiedades:

```js
{
  rawOptions: {...}, // Parámetros originales transmitidos
  options: {...}, // Parámetros validados transmitidos
  src: "...", // Ruta a la imagen generada
  srcSet: {
    values: [...], // Valores generados para srcset, cada entrada tiene una url y un descriptor de tamaño
    attribute: "", // Atributo srcset generado a partir de los valores
  }
  attributes: {...} // Atributos HTML adicionales necesarios para representar la imagen (anchura, altura, estilo, etc.)
}
```

## Texto Alt

No todos los usuarios pueden ver las imágenes de la misma manera, por lo que la accesibilidad es una preocupación especialmente importante al utilizar imágenes. Utiliza el atributo `alt` para proporcionar [texto alternativo descriptivo](https://www.w3.org/WAI/tutorials/images/) para las imágenes.

Este atributo es requerido tanto para los componentes `<Image />` como `<Picture />`. Si no se proporciona texto alternativo, se mostrará un mensaje de error útil recordándote incluir el atributo `alt`.

Si la imagen es meramente decorativa (es decir, no contribuye a la comprensión de la página), establece `alt=""` para que los lectores de pantalla sepan que deben ignorar la imagen.

## Servicio de imágenes por defecto

[Sharp](https://github.com/lovell/sharp) es el servicio de imágenes por defecto utilizado para `astro:assets`. Puedes configurar aún más el servicio de imágenes utilizando la opción [`image.service`](/es/reference/configuration-reference/#imageservice).

:::note
Cuando se utiliza un [administrador de paquetes estricto](https://pnpm.io/pnpm-vs-npm#npms-flat-tree) como `pnpm`, es posible que debas instalar manualmente Sharp en tu proyecto, aunque sea una dependencia de Astro:

```bash
pnpm add sharp
```
:::

### Configura Squoosh

Si prefieres utilizar [Squoosh](https://github.com/GoogleChromeLabs/squoosh) para transformar tus imágenes, actualiza tu configuración con lo siguiente:

```js title="astro.config.mjs" ins={4-6}
import { defineConfig, squooshImageService } from 'astro/config';

export default defineConfig({
  image: {
    service: squooshImageService(),
  },
});
```

### Configura el servicio no-op de paso

Si tu [adaptador para el modo `server` o `hybrid`](https://astro.build/integrations/?search=&categories%5B%5D=adapters) no admite la optimización de imágenes integrada de Astro con Squoosh y Sharp (por ejemplo, Deno, Cloudflare), puedes configurar un servicio de imágenes sin acción para permitirte utilizar los componentes `<Image />` y `<Picture />`. Ten en cuenta que Astro no realiza ninguna transformación ni procesamiento de imágenes en estos entornos. Sin embargo, aún puedes disfrutar de otros beneficios de usar `astro:assets`, como la ausencia de Desplazamiento Acumulativo de Diseño (CLS), el atributo `alt` obligatorio y una experiencia de autoría coherente.

Configura el servicio `passthroughImageService()` para evitar el procesamiento de imágenes de Squoosh y Sharp:

```js title="astro.config.mjs" ins={4-6} "passthroughImageService"
import { defineConfig, passthroughImageService } from 'astro/config';

export default defineConfig({
  image: {
    service: passthroughImageService()
  }
});
```

## Integraciones comunitarias

Existen varias [integraciones de imágenes de la comunidad](https://astro.build/integrations?search=images) de terceros para optimizar y trabajar con imágenes en tu proyecto de Astro.

## Actualizar a v3.0 desde v2.x

`astro:assets` ya no está detrás de una bandera experimental en Astro v3.0.

`<Image />` es ahora un componente integrado y se ha eliminado la integración anterior `@astrojs/image`.

Estos y otros cambios relacionados con el uso de imágenes en Astro pueden causar algunos cambios disruptivos al actualizar tu proyecto de Astro de una versión anterior.

Sigue las instrucciones a continuación según corresponda para actualizar un proyecto de Astro v2.x a v3.0.

### Actualizar desde `experimental.assets`

Si habías habilitado previamente la bandera experimental para `astro:assets`, deberás actualizar tu proyecto para Astro v3.0, que ahora incluye las características de assets de forma predeterminada.

#### Eliminar la bandera `experimental.assets`

Elimina la bandera experimental:

```js title="astro.config.mjs" del={4-6}
import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    assets: true
  }
});
```

Si es necesario, también actualiza tu archivo `src/env.d.ts` para reemplazar la referencia `astro/client-image` por `astro/client`:

```ts title="src/env.d.ts" del={1} ins={2}
/// <reference types="astro/client-image" />
/// <reference types="astro/client" />
```

#### Eliminar el alias de importación `~/assets`

Este alias de importación ya no se incluye por defecto con `astro:assets`. Si estabas usando este alias con assets experimentales, debes convertirlos a rutas de archivo relativas o [crear tus propios alias de importación](/es/guides/aliases/).

```astro title="src/pages/posts/post-1.astro" del={2} ins={3}
---
import rocket from '~/assets/rocket.png'
import rocket from '../../assets/rocket.png';
---
```

#### Agrega soporte sencillo para assets en Cloudflare, Deno, Vercel Edge y Netlify Edge

 Astro v3.0 permite que `astro:assets` funcione sin errores en Cloudflare, Deno, Vercel Edge y Netlify Edge, que no admiten la optimización de imágenes integrada de Astro con Squoosh y Sharp. Ten en cuenta que Astro no realiza ninguna transformación ni procesamiento de imágenes en estos entornos. Sin embargo, aún puedes disfrutar de otros beneficios de usar `astro:assets`, como la ausencia de Desplazamiento Acumulativo de Diseño (CLS), el atributo `alt` obligatorio y una experiencia de autoría coherente.
 
 Si antes evitaste usar `astro:assets` debido a estas limitaciones, ahora puedes usarlo sin problemas. Puedes configurar el servicio de imágenes sin acción para optar explícitamente por este comportamiento:

```js title="astro.config.mjs" ins={4-8}
import { defineConfig } from 'astro/config';

export default defineConfig({
  image: {
    service: {
      entrypoint: 'astro/assets/services/noop'
    }
  }
});
```

### Decide dónde almacenar tus imágenes

Consulta la guía de Imágenes para ayudarte a decidir [dónde almacenar tus imágenes](#dónde-guardar-las-imágenes). Es posible que desees aprovechar las nuevas opciones para almacenar tus imágenes con la flexibilidad adicional que `astro:assets` ofrece. Por ejemplo, las imágenes relativas desde la carpeta `src/` de tu proyecto ahora pueden ser referenciadas en Markdown, MDX y Markdoc utilizando la sintaxis estándar de Markdown `![alt](src)`.

### Actualiza las etiquetas existentes `<img>`

Anteriormente, importar una imagen devolvía un `string` con la ruta de la imagen. Los assets de imagen importados coinciden con la siguiente firma:

```ts
interface ImageMetadata {
  src: string;
  width: number;
  height: number;
  format: string;
}
```

Debes actualizar el atributo `src` de cualquier etiqueta `<img>` existente (incluyendo cualquier [imagen en componentes de frameworks UI](#imágenes-en-componentes-de-frameworks-ui)) y también puedes actualizar otros atributos que ahora están disponibles para ti a partir de la imagen importada.

```astro title="src/components/MyComponent.astro" ".src" ".width" ".height" del={4} ins={6}
---
import rocket from '../images/rocket.svg';
---
<img src={rocket} width="250" height="250" alt="Un cohete en el espacio." />

<img src={rocket.src} width={rocket.width} height={rocket.height} alt="Un cohete en el espacio." />
```

### Actualiza tus archivos Markdown, MDX y Markdoc

Las imágenes relativas desde la carpeta `src/` de tu proyecto ahora pueden ser referenciadas en Markdown, MDX y Markdoc utilizando la sintaxis estándar de Markdown `![alt](src)`.

Esto te permite mover tus imágenes desde el directorio `public/` a la carpeta `src/` de tu proyecto, donde ahora serán procesadas y optimizadas. Tus imágenes existentes en `public/` y las imágenes remotas siguen siendo válidas, pero no son optimizadas por el proceso de compilación de Astro.

```md title="src/pages/posts/post-1.md" "/_astro" ".hash" "../../assets/"
# Mi página Markdown

<!-- ¡Imágenes locales ahora posibles! -->
![Un cielo estrellado](../../images/stars.png)

<!-- ¡Mantén tus imágenes junto a tu contenido! -->
![Un cielo estrellado](./stars.png)
```

Si necesitas más control sobre los atributos de tu imagen, te recomendamos usar el formato de archivo `.mdx`, que te permite incluir el componente `<Image />` de Astro o una etiqueta JSX `<img />` además de la sintaxis Markdown. Utiliza la [integración de MDX](/es/guides/integrations-guide/mdx/) para agregar soporte para MDX a Astro.

### Elimina `@astrojs/image`

Si estabas utilizando la integración de imágenes en Astro v2.x, completa los siguientes pasos:

1. Elimina la integración `@astrojs/image`.

    Debes [eliminar la integración](/es/guides/integrations-guide/#eliminando-una-integración) desinstalándola y luego eliminándola de tu archivo `astro.config.mjs`.

    ```js del={3,7}
    // astro.config.mjs
    import { defineConfig } from 'astro/config';
    import image from '@astrojs/image';

    export default defineConfig({
      integrations: [
        image(),
      ]
    })
    ```

2. Actualiza los tipos (si es necesario).

		Si tenías tipos especiales configurados para `@astrojs/image` en `src/env.d.ts`, es posible que necesites cambiarlos de nuevo a los tipos predeterminados de Astro si la actualización a la versión 3 no completó este paso por ti.

		```ts title="src/env.d.ts" del={1} ins={2}
		 /// <reference types="@astrojs/image/client" />
		 /// <reference types="astro/client" />
		```

		Del mismo modo, actualiza `tsconfig.json` si es necesario:

		```json title="tsconfig.json" del={3} ins={4}
		{
			"compilerOptions": {
			  "types": ["@astrojs/image/client"]
			  "types": ["astro/client"]
			}
		}
		```

3. Migra cualquier componente `<Imagen />` existente.

    Cambia todas las declaraciones de `import` de `@astrojs/image/components` a `astro:assets` para poder usar el nuevo componente integrado `<Image />`.

    Elimina cualquier atributo del componente que no sean [propiedades de assets de imagen actualmente admitidas](/es/guides/images/#propiedades).

    Por ejemplo, `aspectRatio` ya no es compatible, ya que ahora se infiere automáticamente a partir de los atributos `width` y `height`.

      ```astro title="src/components/MyComponent.astro" del= {2,11} ins={3}
      ---
      import { Image } from '@astrojs/image/components';
      import { Image } from 'astro:assets'
      import localImage from "../assets/logo.png";
      const localAlt = "El logo de Astro";
      ---

      <Image
        src={localImage}
        width={300}
        aspectRatio="16:9"
        alt={localAlt}
      />
      ```
      
4. Elige un servicio de imágenes predeterminado.

   [Sharp](https://github.com/lovell/sharp) es ahora el servicio de imágenes predeterminado utilizado para `astro:assets`. Si deseas utilizar Sharp, no se requiere ninguna configuración.

    Si prefieres utilizar [Squoosh](https://github.com/GoogleChromeLabs/squoosh) para transformar tus imágenes, actualiza tu configuración con la siguiente opción `image.service`:

    ```js title="astro.config.mjs" ins={4-6}
    import { defineConfig, squooshImageService } from 'astro/config';

    export default defineConfig({
      image: {
        service: squooshImageService(),
      },
    });
    ```

### Actualiza los esquemas de Colecciones de Contenido

Ahora puedes declarar una imagen asociada para una entrada de colecciones de contenido, como la imagen de portada de una entrada de blog, en tu metadatos usando su ruta relativa a la carpeta actual.

El nuevo helper `image` para colecciones de contenido te permite validar los metadatos de la imagen utilizando Zod. Aprende más sobre [cómo usar imágenes en colecciones de contenido](/es/guides/images/#imágenes-en-colecciones-de-contenido)

### Navegando por las importaciones de imágenes en Astro v3.0

En Astro v3.0, si tienes que conservar el antiguo comportamiento de importación para las imágenes y requieres una representación de tipo string de la URL de la imagen, añade `?url` al final de la ruta de la imagen al importarla. Por ejemplo:

```astro title="src/pages/blog/MyImages.astro"
---
import Sprite from '../assets/logo.svg?url';
---
  <svg>
    <use xlink:href={Sprite + '#cart'} />
  </svg>
```

Este enfoque garantiza que obtengas el string URL. Ten en cuenta que durante el desarrollo, Astro utiliza una ruta `src/`, pero al compilar, genera rutas hash como `/_astro/cat.a6737dd3.png`.

Si prefieres trabajar directamente con el objeto de imagen, puedes acceder a la propiedad `.src`. Este enfoque es el mejor para tareas como la gestión de las dimensiones de la imagen para las métricas de Core Web Vitals y la prevención de CLS.

Si estás en transición al nuevo comportamiento de importación, combinar `?url` y `.src` puede ser el método adecuado para el manejo de imágenes sin problemas.
